---
title: Scroll Plugin
description: Provides the <Scroller /> component and composables for page layout, virtualization, and navigation in Vue.
searchable: true
---

# Scroll Plugin

The Scroll Plugin is a foundational plugin responsible for page layout, virtualization, and navigation. It provides the essential `<Scroller />` component, which intelligently renders only the visible pages to ensure high performance, and the `useScroll` composable for building page navigation controls.

## Installation

This plugin depends on the `Viewport` plugin. You must install both packages.

```sh npm2yarn
npm install @embedpdf/plugin-scroll @embedpdf/plugin-viewport
````

## Registration

Import `ScrollPluginPackage` and its `Viewport` dependency, and add them to the `plugins` array.

```typescript {4, 15-18}
import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/vue'
import { ScrollPluginPackage, ScrollStrategy } from '@embedpdf/plugin-scroll/vue'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),

  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),

  // Register and configure the scroll plugin
  createPluginRegistration(ScrollPluginPackage, {
    strategy: ScrollStrategy.Vertical, // or Horizontal
    initialPage: 1,
  }),
]
```

## Usage

The plugin provides the `<Scroller />` component for rendering pages and the `useScroll` composable for navigation.

### The `<Scroller />` and Scoped Slot

The `<Scroller />` component is the heart of the layout system. It must be placed inside a `<Viewport />`.

Crucially, the `<Scroller />` does not render pages itself. Instead, it calculates *which* pages should be visible and exposes layout data for each one through its default **scoped slot**. This gives you complete control over the content of each page placeholder.

```vue {2, 8}
<script setup lang="ts">
import { RenderLayer } from '@embedpdf/plugin-render/vue';
</script>
<template>
  <Scroller>
    <template #default="{ page }">
      <div :style="{ width: `${page.width}px`, height: `${page.height}px`, position: 'relative' }">
        <RenderLayer :page-index="page.pageIndex" :scale="page.scale" />
      </div>
    </template>
  </Scroller>
</template>
```

### Page Navigation

The `useScroll` composable provides everything you need to build a page navigation UI. It returns a `provides` object with action methods and a reactive `state` object with data like the current page number.

```vue
<script setup lang="ts">
import { useScroll } from '@embedpdf/plugin-scroll/vue';

const { provides: scroll, state } = useScroll();
</script>

<template>
  <div v-if="scroll">
    <span>Page {{ state.currentPage }} of {{ state.totalPages }}</span>
    <button @click="scroll.scrollToNextPage()">Next</button>
  </div>
</template>
```

## Live Example

This example features a complete page navigation component that allows jumping to a specific page and moving forward or backward.

import { ScrollExample } from '../code-examples/scroll-example';

<ScrollExample />

## API Reference

### Configuration (`ScrollPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`strategy`** | `ScrollStrategy` | Sets the scroll direction. Can be `ScrollStrategy.Vertical` or `ScrollStrategy.Horizontal`. <br />**Default**: `ScrollStrategy.Vertical` |
| **`pageGap`** | `number` | The space in pixels between pages or spreads. <br />**Default**: `10` |
| **`initialPage`** | `number` | The 1-based page number to scroll to when a document first loads. |
| **`bufferSize`** | `number`| The number of pages to render outside the visible area for a smoother scrolling experience. <br />**Default**: `2` |

### Component: `<Scroller />`

The virtualized container that lays out pages.

#### Default Scoped Slot Props

| Property | Type | Description |
| :--- | :--- | :--- |
| **`page`** | `object` | An object containing all layout data for the page, including `pageIndex`, `width`, `height`, `scale`, and `rotation`. |

### Composable: `useScroll()`

A convenience composable for building page navigation UIs.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`provides`** | `Ref<ScrollCapability \| null>` | A ref object with methods to control scrolling and navigation. `null` if the plugin is not ready. |
| **`state`** | `Ref<object>` | A ref object containing the current reactive scroll state. |

#### `state` Properties

| Property | Type | Description |
| :--- | :--- | :--- |
| **`currentPage`** | `number` | The current page number that is most visible in the viewport. |
| **`totalPages`** | `number` | The total number of pages in the document. |

#### `provides` Methods (`ScrollCapability`)

| Method | Description |
| :--- | :--- |
| **`scrollToPage(options)`** | Scrolls to a specific page. The `options` object takes a `pageNumber` and optional `behavior: 'smooth'`. |
| **`scrollToNextPage()`** | Scrolls to the next page or spread. |
| **`scrollToPreviousPage()`** | Scrolls to the previous page or spread. |